<html>
<head>
<link rel="stylesheet" type="text/css" media="screen" href="../styles/style.css">
</head>
<body>

<h1>Fizzix Manual</h1>

<a name="about"><h2>About</h2></a>
<p>Welcome to Fizzix, a physics engine with fairly undetermined laws of physics. Fizzix allows the user to change the laws of physics and just see what happens. Gravity as G*M1*M2*R instead of G*M1*M2/R^2? A force that attracts things together if they're pink? How about F = omega*(foo1-foo2)? No problem! </p>
<p>Fizzix was conceived by Anton F., Joey L., Daniel S., Purnima B., and Eric V. for their software design class at Montgomery Blair High School. It is divided into two main parts:</p>
<ul>
	<li><a href=":manual.html#fizzix">fizzix</a> (Front-end)</li>
	<li><a href=":manual.html#libfizzix">libfizzix</a> (Back-end)</li>
</ul>

<a name="libfizzix"><h3>libfizzix</h3></a>
<p>libfizzix does the computations that allow the simulation to run. It is written in C++, and performs one single important function: run one step of the simulation. It gets passed lists of objects, forces, constants, and many other parameters that allow it to determine the state of the Fizzix universe after one time-step has elapsed.</p>

<a name="fizzix"><h3>Fizzix</h3></a>
<p>Fizzix provides a GUI for interfacing with libfizzix. It shows a 3D representation of the universe, and allows the creation of objects that will interact via forces within the universe. It provides controls to alter the flow of time within the universe.</p>

<a name="mainscreen"><h2>Main Screen</h2></a>
<p><img src="main-win.png"></P>
<p>There are four panels on the main screen:</p>
<ul>
	<li>Universe</li>
	<li>Browser</i>
	<li>Editor</li>
	<li>Control bar</li>
</ul>
<p>The Universe window provides a 3D view of the user's objects. This is where the simulation happens. All other panels allow you to alter properties of the Universe. <a href=":manual.html#universe">More on the Universe...</a></p>
<p>The Browser shows lists of things that exist in the universe: Objects, Forces, Macros, and Constants. These lists can be searched and modified. <a href=":manual.html#browser">More on the Browser...</a>.</p>
<p>The Editor allows you to edit the properties of anything that exists in the Universe. By navigating to an element in the Browser and choosing Edit, its properties appear in the Editor. <a href=":manual.html#editor">More on the Editor...</a></p>
<p>The Control bar provides easy simulation control. Here, you can start and stop the simulation, as well as change the properties of the simulator. <a href=":manual.html#controlbar">More on the Control bar...</a></p>

<a name="universe"><h2>Universe</h2></a>
<p>The Universe is where things happen. Objects that you create appear in the universe, and interact with forces you define.</p>
<p>The universe is bounded by a translucent cube. Anything that escapes this cube will cease to exist.</p>
<p>You can control your view of the universe with your mouse or with the menus. Here are some of the actions you can perform:</p>
<table border="1">
	<tr>
		<th>Action</th>
		<th>Mouse</th>
		<th>Menu</th>
	</tr>
	<tr>
		<td>Change camera angle</td>
		<td>Click and drag anywhere</td>
		<td>View &rarr; Camera Presets</td>
	</tr>
	<tr>
		<td>Zoom in or out</td>
		<td>Scroll up or down with mouse wheel</td>
		<td>View &rarr; Zoom</td>
	</tr>
</table>
<p>To create objects in the universe, use the <a href=":manual.html#browser">Browser</a>.</p>
<p>To edit objects in the universe, use the <a href=":manual.html#editor">Editor</a>.</p>
<p>To run the simulation in the universe, use the <a href=":manual.html#controlbar">Control bar</a>.</p>

<a name="browser"><h2>Browser</h2></a>
<p>The Browser lists elements that are at work in the universe.</p>
<p>To browse the four different elements, click the tab that says <a href=":manual.html#objects">Objects</a>, <a href=":manual.html#forces">Forces</a>, <a href=":manual.html#constants">Constants</a>, or <a href=":manual.html#macros">Macros</a>. A list will appear.</p>
<p>To add an element, choose its corresponding tab and click <i>New</i>. Then, type a name for it in the dialog box.</p>
<p><img src="browser-new.png"></P>
<p>To remove an element, find it in the browser and click <i>Delete</i>.</p>
<p>To modify an element's properties, find it in the browser and click <i>Edit</i>. You can then change its properties in the <a href=:manual.html#editor">Editor</a> pane.</p>
<p>To search through elements, begin typing in the <i>Find</i> text box.</p>
<p><img src="browser-find.png"></P>

<a name="editor"><h2>Editor</h2></a>
<p>The Editor lets you change an element's properties.</p>
<p>To choose an element to edit, use the <a href=":manual.html#browser">browser</a>.</p>
</p>Once you are done making changes to an object, click the </i>Save</i> button. This will update the Browser and the Universe.</p>

<h3>Editing Objects</h3>
<p>Under the Shape tab, you can change the shape of the object. For instance, you can make an object a sphere and change its radius to 3.</p>
<P><img src="editor-object-shape.png"></P>
<p>Under the properties tab, you have access to some of the more advanced attributes of the object. You can, for instance, change its position, mass, and color. You can add new properties by clicking the <i>New</i> button. To change a property's value, select it and choose <i>Edit</i>. Properties can be either scalar or vector quantities. To remove a property, click the <i>Delete</i> button.</p>

<h3>Editing Forces and Macros</h3>
<p>Forces and Macros are defined by formulae. You can type a formula into the formula box in the Editor. <a href=":manual.html#formulae">Click here to learn about formulae.</a></p>

<h3>Editing Constants</h3>
<p>A constant can be either a scalar or a vector. Choose the appropriate radio button and enter data into the text boxes.</p>
<p><img src="editor-constant.png"></P>

<a name="controlbar"><h2>Control bar</h2></a>
<p>The Control bar provides simulation control.</p>
<p>On the left, there is a bar showing the status of the Fizzix engine. It will display errors and messages from the simulator.</p>
<p>You can use the buttons to Start, Stop, and Reset the simulation. <i>Reset</i> will revert the universe back to the original state, before it was run.</p>
<p>The <i>time delta</i> input field allows you to change the length of a single step of the universe. Lower dt will allow for more accurate simulation and will be less choppy, but will run much slower and take up more CPU.</p>
<p><img src="controlbar-dt.png"></P>

<a name="objects"><h2>Objects</h2></a>
<p>Objects are elements in the universe that have mass and move around. Objects have <a href=":manual.html#properties">properties</a> and are governed by <a href=":manual.html#forces">forces</a>.</p>
<p>Objects are stored as the triangles forming their surface, and are assumed to have uniform density. Triangles have no torque, but varying forces on an object's triangles will exert a torque on the whole object.</p>

<a name="forces"><h2>Forces</h2></a>
<p>Forces describe how <a href=":manual.html#objects">objects</a> interact in the universe. A force always acts between two objects. A force is defined by a <a href=":manual.html#formulae">formula</a> that may involve properties of the objects on which it is working, universal constants, or sub-formulae called <a href=":manual.html#macros">macros</a>.</p>
<p>Forces are either evaluated from an object's center of mass, or from its individual triangles. If a force is only calculated from the center of mass, no torque is applied. However, calculating forces from triangles is computationally intensive, and generalizing objects to their center of mass can greatly reduce CPU load.</p>
<p>If a force's formula evaluates to a vector, that is the exact force which is applied. If a force evaluates to a scalar, it is multiplied by r-hat to obtain a vector (the force is assumed to act towards the second object).</p>

<a name="macros"><h2>Macros</h2></a>
<p>Macros are sub-formulae inside of <a href=":manual.html#forces">forces</a> that provide common expressions, such as the distance formula. They can be used to make formulae neater, and can speed up the simulation if the value is used often.</p>

<a name="constants"><h2>Constants</h2></a>
<p>Constants are important and universal values, such as the gravitational constant G.</p>
<p>Using named constants allows you to change a value used in many formulas just once, and have it update automatically. Sometimes there is no need to create a named constant, e.g. the number two, but often it makes formulae more readable and maintainable.</p>
<p>Constants can be either scalars or vectors.</p>

<a name="formulae"><h2>Formulae</h2></a>
<p>Formulae are user-defined expressions that describe a  <a href=":manual.html#forces">force</a> or a  <a href=":manual.html#macro">macro</a>.</p>
<p>Formulae are entered in prefix LISP notation: (operator operand operand ...)</p>
<p>A list of operators is coming soon.</p>
<p>Operands may be any of the following:</p>
<ul>
	<li>Anonymous scalar constant. Examples: 2, -3, 5.7</li>
	<li><a href=":manual.html#forces">Force</a> names enclosed in braces. Examples: {gravity}, {electrostatic}, {magnetism}</li>
	<li><a href=":manual.html#macros">Macro</a> names enclosed in square brackets. Examples: [distance], [r-hat], [velocity_difference]</li>
	<li>Property of the act<b>or</b> object, prefixed with a $. Examples: $SYSTEM_mass, $SYSTEM_position, $SYSTEM_color</li>
	<li>Property of the act<b>ed</b> object, prefixed with an @. Examples: @SYSTEM_mass, @SYSTEM_position, @SYSTEM_color</li>
</ul>
<p>Examples:</p>
<pre>
Gravity:
(* $SYSTEM_mass @SYSTEM_mass "G" (^ [distance] -2))
</pre>
</body>
</html>
